Skip to content

feat: vana CLI v1#56

Merged
tnunamak merged 249 commits intomainfrom
feat/connect-cli-v1
Mar 18, 2026
Merged

feat: vana CLI v1#56
tnunamak merged 249 commits intomainfrom
feat/connect-cli-v1

Conversation

@tnunamak
Copy link
Member

@tnunamak tnunamak commented Mar 12, 2026

Summary

The vana CLI for personal data portability. Connect platforms, collect data, inspect it locally, sync to a Personal Server.

What's in this PR

CLI core

  • vana connect [source] -- connect a platform and collect data
  • vana collect [source] -- re-collect from a connected source
  • vana sources -- browse available platforms
  • vana status -- connection health dashboard
  • vana data list/show/path -- inspect collected datasets
  • vana doctor, vana logs, vana setup

Background and scheduling

  • --detach for background collection
  • vana schedule add/list/remove -- OS-native scheduling (launchd/cron)
  • Connection health model: healthy/needs_reauth/error/stale

Agent integration

  • vana mcp -- MCP server with 6 tools
  • vana skills list/install/show -- installable agent skills
  • --ipc mode for file-based credential exchange
  • Three bundled skills: connect-data, create-connector, next-prompt

Visual design

  • Custom heartbeat bloom spinner
  • Vana brand palette, scope manifest, CLI-DESIGN-SKILL.md

Infrastructure

  • Per-source result storage at ~/.vana/results/
  • Auto-migration from ~/.dataconnect with DataConnect symlink
  • Homebrew formula auto-sync in CI
  • Personal Server scope-aware ingest

Research

  • Personal data as agent context (158 findings)
  • Async CLI patterns (105 findings, 11 reference CLIs)
  • Auth expiry patterns (Plaid, Stripe, MX)

Risk to SDK

SDK entry points (src/server/, src/react/, src/index.ts) are untouched. Zero changes to the published @opendatalabs/connect API.

Verification

pnpm validate, vana connect github, vana status, vana skills list

186 tests passing.

@vercel
Copy link

vercel bot commented Mar 12, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
connect Ready Ready Preview Mar 18, 2026 10:53pm

Request Review

tnunamak and others added 28 commits March 18, 2026 00:26
Teach agents to generate their next task from connected personal
data. The skill reads ~/.vana/results/*.json, parses timestamps
for recency, applies user guidance from ~/.vana/next-prompt.md,
and generates 1-3 prioritized suggestions.

The config file (~/.vana/next-prompt.md) is the user's control
surface: priorities, standing instructions, and notification
preferences. The user edits it directly or asks the agent to
update it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The data-show-github command can fail in CI when no seeded data
exists. Mark it allowFailure: true. Also update the log path
normalizer regex for ~/.vana (was ~/.dataconnect).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
These commands fail in CI where no collected data or browser exists.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…cripts

Update VHS fixture directory, transcript paths, all documentation
references, and utility scripts to use ~/.vana consistently.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Skill list: one line per skill, "installed" badge in accent blue.
No descriptions (use vana skill show for detail). Matches the
compact list pattern.

Skill install: success line + next step only. No file paths.
Suggests installing the next uninstalled skill instead of
circular vana skill list.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Async/background connect, scheduled collection, SEA stack trace,
stale transcripts, date filtering, data versioning.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Stale SingletonLock after interrupted connect, agent-friendly
credential passing, MCP auth mode check, skill composition
boundaries.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add IPC mode issue: expose existing file-based requestInput IPC
(pending-input/input-response JSON files) as a CLI mode so agents
can handle credential prompts without interactive stdin.

connect-data skill: check auth mode first, run interactive sources
in foreground (not background), tell user to run legacy sources
themselves.

next-prompt skill: never attempt connections, work with available
data only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
IPC mode (--ipc): connectors pause and write credential questions
to ~/.vana/pending-input-{runId}.json, then poll for the agent's
response at ~/.vana/input-response-{runId}.json. Enables agents
to handle auth without interactive stdin. 5-minute timeout.

Stale lock cleanup: remove SingletonLock before every browser
launch, preventing "Failed to create ProcessSingleton" errors
after interrupted connects.

MCP auth check: connect_source tool checks authMode before
spawning. Legacy (browser) sources return immediately with
instructions for the user instead of hanging.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The skill now tells agents to use `vana connect <source> --json --ipc`
which writes credential prompts to files instead of stdin. Agents
poll for pending-input files, ask the user, and write response files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The agent MUST use run_in_background for --ipc connects, then
immediately read the task output for needs-input events. Explicit
step-by-step flow covering background start, output reading,
credential collection, response writing, and 2FA re-prompts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
30 minutes gives the agent enough time to ask the user for
credentials and handle multi-step auth (2FA). Previously 5
minutes caused timeouts during normal agent-user interaction.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three-round design analysis (brainstorm > design > plan > assess)
informed by 68 findings across 11 reference CLIs. Conclusion:
blocking is correct for <5 minute operations. No --detach for v1.

next-prompt skill: added freshness check — suggests recollection
when data is >24h old. collect --all already exists.

Research artifacts in research/async-cli/.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
--detach: spawns a background process for long-running connects
(ChatGPT takes 30 minutes). Parent exits immediately, child
writes progress to ~/.vana/sessions/. vana status shows active
background connections.

Connection health: each source tracks healthy/needs_reauth/error/
stale based on actual collection results. vana status shows health
per source with colored indicators. When a source needs re-auth,
status prominently surfaces it.

vana schedule: OS-native scheduling via launchd (macOS) or crontab
(Linux). schedule add --every 24h installs a recurring collection.
schedule list shows active schedules. schedule remove uninstalls.
No custom daemon — the OS is the scheduler.

Design informed by 105 research findings across Plaid, Stripe, MX,
PM2, Turborepo, Docker, Vercel, Railway, and 7 other reference
CLIs/services. Three-round design analysis in
research/async-cli/daemon-design-rounds.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Auth expiry: Plaid three-tier health model, advance warning webhooks,
MX 13+ connection statuses, Google silent revocation triggers,
Strava rotating refresh tokens, cross-platform re-auth UX patterns.

Daemon patterns: PM2 dual-socket architecture, Turborepo on-demand
daemon with graceful degradation, Docker socket activation, Homebrew
services OS wrapper, Bree/Croner job schedulers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Detached processes have no stdin and nobody watching. If auth is
needed, fail fast and record needs_reauth (Plaid's pattern: fail
the fetch, record state, let user re-auth at convenience).

Pre-check: refuse to detach if source has never been connected.
"Run vana connect <source> first to authenticate."

--ipc remains separate for agents actively watching (Claude Code
background task flow). --detach is for fire-and-forget.

Design analysis in research/async-cli/detach-ipc-design.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Homebrew formula, hosted installer, and demo assets can go stale
when canary releases don't trigger downstream sync. Document the
full distribution chain that needs automation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Homebrew: trigger formula sync from CI after verify-prerelease-install.
Eliminates the race window where binaries update before the formula,
causing checksum mismatch on brew install.

Error results: detect connector results that are error objects
(e.g. {"error":"Could not determine username"}) and report failure
instead of declaring success.

Sources list: show all sources with descriptions instead of
collapsing after 3. Users were confused by the collapsed line.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add checkLegacyDataHome() that detects ~/.dataconnect without
auto-migrating. The CLI informs the user and tells them how to
move their data. No silent renames, no side effects in path
getters.

Remove shipped items from open issues: IPC mode, stale lock
cleanup, MCP auth check, skill composition, agent credential
passing, homebrew auto-sync.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
On first run, if ~/.dataconnect exists and ~/.vana doesn't:
rename to ~/.vana and create a symlink at ~/.dataconnect pointing
to ~/.vana. DataConnect (which references ~/.dataconnect) follows
the symlink. Both apps share the same data.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Stripe/Vercel convention: plural nouns for resource commands.
sources, skills, not source, skill.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The list showed display names ("Next Prompt") but install needs
IDs ("next-prompt"). Now shows IDs directly. Guessable commands.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Auth mode detection checked the local data-connectors checkout
which could be stale (showing legacy when connectors were already
modernized to requestInput). Now checks the connector cache first
(populated by vana connect's auto-fetch), falls back to local
checkout only if not cached.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CLI README at cli/README.md with current connect output (heartbeat
spinner, scope manifest), full command table including new commands
(--detach, schedule, skills, mcp, collect), updated source list.

Root README points to cli/README.md. Clean separation for future
repo split.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When ~/.vana exists but ~/.dataconnect doesn't (new CLI user),
create a symlink so DataConnect desktop app finds the data.
DataConnect hardcodes ~/.dataconnect in connector.rs:66 and
should adopt ~/.vana upstream.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
158 deduplicated findings across auth expiry, agent autonomy,
memory infrastructure, personal AI products, and competitive
landscape. Three artifacts: landscape CSV (40 rows), landscape
report (505 lines), executive memo (72 lines).

Research informs the next-prompt skill and vana next feature
design. Key finding: no product combines cross-platform personal
data with coding agent context.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove superseded docs (CLI-README.md, CLI-README-launch.md,
EXECUTION-CONTEXT-MEMO.md). Move docs/research/ to
research/cli-design/ alongside async-cli and personal-data-agents.
Add creation datestamps to 10 docs that were missing them.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
GITHUB_TOKEN lacks permission to dispatch workflows in
vana-com/homebrew-vana. Use a fine-grained PAT with Actions
write scope on that repo.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@vana-connect-release-bot
Copy link

🎉 This PR is included in version 0.9.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant